% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_distance_mean_by_group.R
\name{plot_distance_by_group}
\alias{plot_distance_by_group}
\title{Avg distance of each demog group (of multiple groups) - Table or Plot}
\usage{
plot_distance_by_group(
  results_bybg_people,
  demogvarname = NULL,
  demoglabel = fixcolnames(demogvarname, "r", "shortlabel"),
  graph = TRUE,
  returnwhat = "table"
)
}
\arguments{
\item{results_bybg_people}{data.table from \code{doaggregate()$results_bybg_people}}

\item{demogvarname}{vector of column names like "pctlowinc" etc.}

\item{demoglabel}{vector of labels like "Low Income Residents" etc.}

\item{graph}{logical optional, set to FALSE to not show the barplot and only save the file of it}

\item{returnwhat}{If returnwhat is "table", invisibly returns a
data.frame with group, ratio, avg_distance_for_group, avg_distance_for_nongroup.
If returnwhat is "plotfilename" then it returns the full path including filename of a .png in a tempdir
If returnwhat is "plot" then it returns the plot object as needed for table_xls_format() ?}
}
\value{
see parameter returnwhat
}
\description{
Shows distance to sites, for residents in each demographic group (vs everyone else).
plot_distance_mean_by_group() and plot_distance_by_group() are synonymous.
}
\details{
Note that the ratio shown is a ratio of distance among others to distance of a given group,
so values below 1 mean the given demographic group lives closer to facilities.
A value of 0.85 would mean the group is only 85\% as far from a site as everyone else.

Note it is in miles assuming input was in miles, and the distance for each resident is
actually the average distance of all residents within their Census block (not block group),
and when a site is very close to the block internal point (like a centroid)
relative to the size of the block, the distance to the average resident in the block is
estimated as 90 percent of the effective radius, which is what the radius of the block
would be if it were the same area in square meters or miles but circular in shape.

This is the approach used in EJScreen to estimate average proximity of a block resident in
cases where the block is extremely close to the site or the site may actually be inside the block,
or exactly on top of the internal point of the block, in which case zero would not be an
appropriate estimate of the distance, hence this adjustment is made in EJAM \code{\link[=getblocksnearby]{getblocksnearby()}}
}
\examples{
 y <- ejamit(testpoints_100, radius = 3)
 
 # see barplot and table comparing groups to see which are closer to sites analyzed
 plot_distance_mean_by_group(y$results_bybg_people) # or distance_mean_by_group() synonym
 
 # table - proximity of sites for just one demog group vs rest of population
 print(distance_by_group(y$results_bybg_people,
   demogvarname = 'pctlowinc'))
   
 # plot cumulative share of group by distance vs overall population
  distance_by_group_plot(y$results_bybg_people,
     demogvarname = 'pctlowinc' )
     
 # plot cum. shares for two groups  
 # about 14\% of black and 12\% of asian residents have a site within 1 mile. 
 # 29\% vs 21\% have a site within 1.5 miles.
 round(xyz[findInterval(c(1, 1.5),  xyz$dist), ], 3) 
 
 # plot is too busy for all groups at once so this is a way to tap through them 1 by 1
 these = c(names_d, names_d_subgroups)
 for (i in 1:length(these)) {
   readline("press any key to see the next plot")
   print(distance_by_group_plot(y$results_bybg_people, demogvarname = these[i]) )
 }
 

}
\seealso{
\code{\link[=distance_by_group]{distance_by_group()}} \code{\link[=distance_by_group_plot]{distance_by_group_plot()}}
}
